PKCS#11 state management functions
This section describes functions that allow the functionality module (FM) to ask the firmware to associate user data with certain firmware structures. The firmware guarantees cleanup of the associated buffer when the structure in question is destroyed. The freeing of the user data is performed by a callback to a user function. If the data is allocated using malloc(), and it contains no pointers to other allocated structures, the free function is typically the standard free() function.
FM_SetAppUserData
This function can be used to associate user data with the calling application. The data is associated with the PID of the calling application. The function specified in this call will be called to free the data when the last application using the library finalizes (for example, when it calls C_Finalize()).
If the application already has associated user data, it will be freed (by calling the current free function) before the new data association is created.
Synopsis
#include <objstate.h>
CK_RV FM_SetAppUserData(FmNumber_t fmNo,
CK_VOID_PTR userData,
CK_VOID (*freeUserData)(CK_VOID_PTR));
| Parameter | Description |
|---|---|
fmNo |
The fm number of the caller. It must be FM_NUMBER_CUSTOM_FM in this release of the software. |
userData |
Address of the memory block that will be associated with the session handle. if it is NULL, the current associated buffer is freed. |
freeUserData |
Address of a function that will be called to free the userData if the library decides that it should be freed. it must be non-NULL if userData is not NULL. |
Return code
CKR_OK: The operation was successful.
CKR_ARGUMENTS_BAD: freeUserData was NULL, when userData was not NULL, or fmNo was not FM_NUMBER_CUSTOM_FM.
CKR_CRYPTOKI_NOT_INITIALIZED: Cryptoki is not yet initialized.
FM_GetAppUserData
This function is used to obtain the userData associated with the current application. If there are no associated buffers, NULL is returned in ppUserData.
Synopsis
#include <objstate.h>
CK_RV FM_SetAppUserData(FmNumber_t fmNo,
CK_VOID_PTR_PTR ppuserData);
| Parameter | Description |
|---|---|
fmNo |
The fm number of the caller. It must be FM_NUMBER_CUSTOM_FM in this release of the software. |
ppuserData |
Address of a variable (of type CK_Void_PTR) which will contain the address of the user data if this function returns CKR_OK. It must be non-NULL. |
Return code
CKR_OK: The operation was successful. The associated user data is placed in the variable specified by ppUserData.
CKR_ARGUMENTS_BAD: ppUserData was NULL, or fmNo was not FM_NUMBER_CUSTOM_FM.
CKR_CRYPTOKI_NOT_INITIALIZED: Cryptoki is not yet initialized.
FM_SetSlotUserData
This function can be used to associate user data with a slot. The data is associated with the slot identified by slotId. The function specified in this call will be called to free the data when the last application using the library finalizes.
If the slot already has associated user data it will be freed, by calling the current free function, before the new data association is created.
Synopsis
#include <objstate.h>
CK_RV FM_SetSlotUserData(FmNumber_t fmNo,
CK_SLOTID slotId,
CK_VOID_PTR userData
CK_VOID(*freeUserData)(CK_VOID_PTR));
| Parameter | Description |
|---|---|
fmNo |
The fm number of the caller. It must be FM_NUMBER_CUSTOM_FM in this release of the software. |
slotId |
The slot ID of the slot. |
userData |
Address of the memory block that will be associated with the session handle. If it is NULL, the current associated buffer is freed. |
freeUserData |
Address of a function that will be called to free the userData, if the library decides that it should be freed. It must be non-NULL if userData is not NULL. |
Return code
CKR_OK: The operation was successful.
CKR_ARGUMENTS_BAD: freeUserData was NULL, when userData was not NULL, or fmNo was not FM_NUMBER_CUSTOM_FM.
CKR_CRYPTOKI_NOT_INITIALIZED: Cryptoki is not yet initialized.
FM_GetSlotUserData
This function is used to obtain the userData associated with the specified slot. if there are no associated buffers, NULL is returned in ppUserData.
Synopsis
#include <objstate.h>
CK_RV FM_GetSlotUserData(FmNumber_t fmNo,
CK_SLOTID slotId,
CK_VOID_PTR userData
CK_VOID_PTR_PTR ppUserData);
| Parameter | Description |
|---|---|
fmNo |
The fm number of the caller. It must be FM_NUMBER_CUSTOM_FM in this release of the software. |
slotId |
The slot ID indicating the slot to be used. |
ppuserData |
Address of a variable (of type CK_Void_PTR) which will contain the address of the user data if this function returns CKR_OK. It must be non-NULL. |
Return code
CKR_OK: The operation was successful. The associated user data is placed in the variable specified by ppUserData.
CKR_ARGUMENTS_BAD: ppUserData was NULL or fmNo was not FM_NUMBER_CUSTOM_FM.
CKR_SLOT_ID_INVALID: The specified slot ID is invalid.
CKR_CRYPTOKI_NOT_INITIALIZED: Cryptoki is not yet initialized.
FM_SetTokenUserData
This function can be used to associate user data with a token. The data is associated with the token in slotId by the library. The function specified in this call will be called to free the data when the last application using the library finalizes, or when the token is removed from that slot.
If the token already has associated user data it will be freed, by calling the current free function, before the new data association is created.
Synopsis
#include <objstate.h>
CK_RV FM_SetTokenUserData(FmNumber_t fmNo,
CK_SLOTID slotId,
CK_VOID_PTR userData
CK_VOID(*freeUserData)(CK_VOID_PTR));
| Parameter | Description |
|---|---|
fmNo |
The fm number of the caller. It must be FM_NUMBER_CUSTOM_FM in this release of the software. |
slotId |
The slot ID of the slot containing the token. |
userData |
Address of the memory block that will be associated with the session handle. if it is NULL, the current associated buffer is freed. |
freeUserData |
Address of a function that will be called to free the userData, if the library decides that it should be freed. It must be non-NULL if userData is not NULL. |
Return code
CKR_OK: The operation was successful.
CKR_ARGUMENTS_BAD: freeUserData was NULL or fmNo was not FM_NUMBER_CUSTOM_FM.
CKR_SLOT_ID_INVALID: The specified slot ID is invalid.
CKR_TOKEN_NOT_PRESENT: The specified slot does not contain a token.
CKR_CRYPTOKI_NOT_INITIALIZED: Cryptoki is not yet initialized.
FM_GetTokenUserData
This function is used to obtain the userData associated with the specified token. If there are no associated buffers, or if the token is not present, NULL is returned in ppUserData.
Synopsis
#include <objstate.h>
CK_RV FM_GetTokenUserData(FmNumber_t fmNo,
CK_SLOTID slotId,
CK_VOID_PTR_PTR ppUserData);
| Parameter | Description |
|---|---|
fmNo |
The fm number of the caller. It must be FM_NUMBER_CUSTOM_FM in this release of the software. |
slotId |
The slot ID of the slot containing the token. |
ppuserData |
Address of a variable (of type CK_VOID_PTR) which will contain the address of the user data if this function returns CKR_OK. It must be non-NULL. |
Return code
CKR_OK: The operation was successful.
CKR_ARGUMENTS_BAD: ppUserData was NULL or fmNo was not FM_NUMBER_CUSTOM_FM.
CKR_SLOT_ID_INVALID: The specified slot ID is invalid.
CKR_CRYPTOKI_NOT_INITIALIZED: Cryptoki is not yet initialized.
FM_SetTokenAppUserData
This function can be used to associate user data with a token in the context of the calling application. The data is associated with the token (token, PID) pair. The function specified in this call will be called to free the data when the last application using the library finalizes, or when the token is removed from that slot.
If the token already has associated user data it will be freed, by calling the current free function, before the new data association is created.
Synopsis
#include <objstate.h>
CK_RV FM_SetTokenAppUserData(FmNumber_t fmNo,
CK_SLOTID slotId,
CK_VOID_PTR userData
CK_VOID(*freeUserData)(CK_VOID_PTR));
| Parameter | Description |
|---|---|
fmNo |
The fm number of the caller. It must be FM_NUMBER_CUSTOM_FM in this release of the software. |
slotId |
The slot ID of the slot containing the token. |
userData |
Address of the memory block that will be associated with the session handle. if it is NULL, the current associated buffer is freed. |
freeUserData |
Address of a function that will be called to free the userData, if the library decides that it should be freed. It must be non-NULL if userData is not NULL. |
Return code
CKR_OK: The operation was successful.
CKR_ARGUMENTS_BAD: freeUserData was NULL or fmNo was not FM_NUMBER_CUSTOM_FM.
CKR_SLOT_ID_INVALID: The specified slot ID is invalid.
CKR_TOKEN_NOT_PRESENT: The specified slot does not contain a token.
CKR_CRYPTOKI_NOT_INITIALIZED: Cryptoki is not yet initialized.
FM_GetTokenAppUserData
This function is used to obtain the userData associated with the specified token in the application context. If there are no associated buffers, or if the token is not present, NULL is returned in ppUserData.
Synopsis
#include <objstate.h>
CK_RV FM_GetTokenAppUserData(FmNumber_t fmNo,
CK_SLOTID slotId,
CK_VOID_PTR_PTR ppUserData);
| Parameter | Description |
|---|---|
fmNo |
The fm number of the caller. It must be FM_NUMBER_CUSTOM_FM in this release of the software. |
slotId |
The slot ID of the slot containing the token. |
ppuserData |
Address of a variable (of type CK_VOID_PTR) which will contain the address of the user data if this function returns CKR_OK. It must be non-NULL. |
Return code
CKR_OK: The operation was successful.
CKR_ARGUMENTS_BAD: ppUserData was NULL or fmNo was not FM_NUMBER_CUSTOM_FM.
CKR_SLOT_ID_INVALID: The specified slot ID is invalid.
CKR_CRYPTOKI_NOT_INITIALIZED: Cryptoki is not yet initialized.
FM_SetSessionUserData
This function can be used to associate user data with a session handle. The data is associated with the (PID, hSession) pair by the library. The function specified in this call will be called to free the user data if the session is closed (via a C_CloseSession() or a C_CloseAllSessions() cal), or the application owning the session finalizes.
If the session handle already contains user data it will be freed, by calling the current free function, before the new data association is created.
Synopsis
#include <objstate.h>
CK_RV FM_SetSessionUserData(FmNumber_t fmNo,
CK_SESSION_HANDLE hSession,
CK_VOID_PTR userData,
CK_VOID (*freeUserData)(CK_VOID_PTR));
| Parameter | Description |
|---|---|
fmNo |
The fm number of the caller. It must be FM_NUMBER_CUSTOM_FM in this release of the software. |
hSession |
A session handle, which was obtained from an C_OpenSession() call. The validity of this parameter is checked. |
userData |
Address of the memory block that will be associated with the session handle. if it is NULL, the current associated buffer is freed. |
freeUserData |
Address of a function that will be called to free the userData, if the library decides that it should be freed. It must be non-NULL if userData is not NULL. |
Return code
CKR_OK: The operation was successful.
CKR_ARGUMENTS_BAD: freeUserData was NULL or fmNo was not FM_NUMBER_CUSTOM_FM.
CKR_SESSION_HANDLE_INVALID: The specified session handle is invalid.
CKR_CRYPTOKI_NOT_INITIALIZED: Cryptoki is not yet initialized.
FM_GetSessionUserData
This function is used to obtain the userData associated with the specified session handle. If there are no associated buffers, NULL is returned in ppUserData.
Synopsis
#include <objstate.h>
CK_RV FM_GetSessionUserData(FmNumber_t fmNo,
CK_SESSION_HANDLE hSession,
CK_VOID_PTR_PTR ppUserData);
| Parameter | Description |
|---|---|
fmNo |
The fm number of the caller. It must be FM_NUMBER_CUSTOM_FM in this release of the software. |
hSession |
A session handle, which was obtained from an C_OpenSession() call. The validity of this parameter is checked. |
ppuserData |
Address of a variable (of type CK_VOID_PTR) which will contain the address of the user data if this function returns CKR_OK. It must be non-NULL. |
Return code
CKR_OK: The operation was successful. The associated user data is placed in the variable specified by ppUserData.
CKR_ARGUMENTS_BAD: ppUserData was NULL or fmNo was not FM_NUMBER_CUSTOM_FM.
CKR_SESSION_HANDLE_INVALID: hSession is not a valid session handle.
